
                 IPC Message and Item Standard ID Codes
                 ======================================

                            -- May 1989 --

In a general InterProcess Communication system, messages should be able
to contain or reference any kind of data relevant to that communication,
from short text strings -- or even single-word codes -- to large bitmaps;
each Server must know exactly what it is being passed.  One major goal
of this IPC design is to make every message totally self-specifying, so
that a Server receiving it can tell immediately what it contains and what
to do with it (or alternatively that it does not recognize it and should
reject it).  This is achieved by providing IDs both for the message as
a whole and the items within it (as well as Flag fields -- described
elsewhere -- that complete the information).  Some of these IDs will be
relevant to individual Server functions, and will be defined by the
developer, but others should have the same meaning wherever they are
used, across the whole system.

For a full description of the IPCMessage structure please refer to the IPC
Manual.  This note just lists the current set of IDs reserved for general
use, and mentions some others that may be useful to adopt.

Remember that each ID is actually a 32-bit word, constructed from four
upper-case ASCII characters (in standard 68000 data order, with the first
character in the leftmost, most significant, 8 bits).  You can conveniently
construct a fixed ID for your program with the MAKE_ID macro defined in
IPC.h, or generate one at run-time with the MakeIPCId() library call.

Message IDs and Item IDs are distinct (though the same code value may be
used for both on occasion).  The list below deals with Message IDs first,
reserved codes followed by suggested ones, then deals similarly with
Item IDs.


Globally Reserved IPCMessage IDs:
================================

These IDs should not be given other meanings anywhere.  Only a few such
seem necessary at the moment.


    QUIT    --  Terminate program.
                Every Server should respond to this one, but the actual
                sequence of actions will have to depend on the situation:
                some Servers may have to defer exiting until they have
                finished any outstanding processing, others may just be
                able to reject any unanswered messages.  The Server may
                also have been asked to pass QUIT messages to others when
                it receives one itself.  A QUIT message may well have no
                items, but in some cases a single item may be included
                whose ID indicates more specific orders, such as:

                            IDLE    -- only quit if currently idle;
                            QUIT    -- orderly exit NOW;
                            PANC    -- get out now -- don't bother to
                                       clean up! (only for debugging really).


    CMND    --  General (standard format) Command message.
                Contains a program command in one of a small set of
                standard formats (probably can be considered equivalent
                to an ARexx message).  The first item will always be the
                command selector -- either a short ASCII string or a
                (32-bit) code word; its meaning will of course be a
                function of the Server.  Any arguments will be in the items
                following this; the actual contents and IDs of these will
                depend on the Server and the Clients it is intended to
                service, but for general servers they will probably just
                be strings.  Likely IDs (see Item IDs below):

                Command Selector:   CODE, STRG.
                Arguments:          STRG, LINE. TEXT, INTG, REAL, CODE, etc.


    MGMT    --  Management -- general requests to control IPC environment.
                This is not well defined at the moment, but we reserve it
                now, knowing that we'll need it later.  Possible items in
                this type of message include:

                        REQQ    --  Request that a QUIT message be sent to
                        a specified IPCPort when this Server terminates.
                        (Further specification of this still to come --
                        for now assume just that ii_Ptr points to the port.)

                        MFIX    -- Memory fixing option; controls whether
                        Server will exit when there are no Clients or
                        remain in memory for later rapid response.  If Ptr
                        field contains TRUE, Server will be fixed; if it is
                        FALSE, Server will be freed.



Suggested message IDs:
=====================

These aren't globally reserved, being specific to Server Ports -- and
tentative in many cases --, but if they seem suitable it would probably be
a good idea to use them.

    OUTA    --  send to output stream in ASCII (whatever output the Server
                generates based on the message, and whatever the Server's
                output stream currently is.)

    OUTB    --  send to output stream in Binary.

    CNVA    --  Convert to ASCII (whatever items, such as INTG and REAL,
                the Server is designed to handle; the resulting string may
                be passed back to the Client, or its disposition may be
                specified in the message -- see the demo "Print Format
                Server").

    MENU    --  request Menu setup (to be described elsewhere).

    MENI    --  request Menu Item setup ( "   " ).


                                # # #


Globally Reserved IPCItem IDs:
=============================

These should only be used -- in ANY message -- with the meanings specified
here.  (Most Servers will only expect to encounter a small subset of them.)
Most of them should be self-explanatory.

    LINE    --  A (complete) line of text -- null terminated, newline
                omitted.

    STRG    --  A null terminated text string -- no newlines (i.e. part of a
                line)

    TEXT    --  An arbitrary block of text -- may have newlines (or
                control characters etc.)

    PORT    --  An IPCPort pointer (A Server that intends to use this MUST
                call UseIPCPort() before replying the message this is in).

    MESG    --  A pointer to an IPCMessage block (with restrictions -- to be
                detailed later).

    CODE    --  A 32-bit code value (maybe an IPC ID)

    FILH    --  An AmigaDOS FILe Handle

    INTG    --  A (32-bit) INTeGer

    CHAR    --  single 8-bit character (in low byte)

    REAL    --  pointer to an IEEE floating point number (double)

    PRVT    --  private item of concern to originating client only. (Can
                be used by a Client to mark a message for later
                identification, with a sequence number, for instance.)

    NULL    --  what it says -- used as a spacer or for cancelling things
                without having to rebuild the message.



Other suggested string valued Items:
===================================

(currently used, or intended to be)

    RETS    --  RETurn String  (a slot provided by the Client for the
                Server to fill in; it may initially either be empty, in
                which case the Server allocates suitable memory, or already
                allocated, in chich case the Server will write into it
                -- taking care not to overflow, of course!).


    FILN    --  FILe Name

    DIRN    --  DIRectory Name

    PATS    --  PATtern String (possibly containing special pattern
                characters; the actual format would be Server -- and
                Message ID -- dependent; e.g. it might be a 'printf' type
                format, or a regular-expression pattern matching string).


Other possible item IDs:
=======================

(currently used in at least one program)

    MARK    --  32-bit private client code to be copied to any message
                generated on the basis of this one; in other words the
                Server generates one or more new messages, from some or
                all of the items in this one, which will eventually get
                back to the Client; the Client can use this item to
                determine the original source, for example to put it in
                the correct list.  This ID may be globally reserved
                eventually.


                                # # #

